Skip to content

feat!: reduce devframe + @devframes/hub public API surface for 0.9 - #190

Open
antfubot wants to merge 5 commits into
mainfrom
feat/0.9-api-surface
Open

feat!: reduce devframe + @devframes/hub public API surface for 0.9#190
antfubot wants to merge 5 commits into
mainfrom
feat/0.9-api-surface

Conversation

@antfubot

Copy link
Copy Markdown
Collaborator

What

Trims the published API surface of devframe and @devframes/hub down to what integrations actually consume, and moves the primary authoring helper to the package root. Part of the 0.9 breaking-cleanup release (extends #180); every change is documented in docs/guide/migration-0.9.md.

Design was worked out via a full consumer audit across the in-repo plugins/* / examples/* / packages/* and the canonical external consumer vitejs/devtools. The plan lives at plans/032-0.9-public-api-surface-reduction.md.

Changes

devframe

  • defineDevframe moves to the devframe root entry (next to defineRpcFunction); devframe/types is now strictly type-only. devframe is the canonical import for both values and types. Previously the primary authoring function was only reachable via devframe/types (the type declaration even leaked onto the root .d.ts while the runtime value did not — now consistent).
  • Removes dead subpaths with no consumers: devframe/adapters/embedded (a one-liner around def.setup(ctx)), devframe/utils/hash, devframe/utils/promise, devframe/utils/scope.
  • Slims devframe/node to the server-assembly surface, dropping 9 internal exports (the diagnostics/services/views host classes, the shared-state/streaming/scope/settings factories, and the toDialableHost/formatHostForUrl helpers).

@devframes/hub

  • Exports DEFAULT_CATEGORIES_ORDER only from @devframes/hub/constants (its documented single source of truth); drops the redundant re-exports from ., /node, /client.

Kept deliberately (the low-level layer the ergonomic APIs and hosts build on): devframe/node/auth, devframe/rpc/client + rpc/transports/ws-client, rpc/server + ws-server, rpc/transports/ws-bun, the utils/{crypto-token,structured-clone,streaming-channel,agent-tool-name} primitives, and — in the node barrel — createContextRpcServer, DevframeAgentHost, and coerceAgentPositionalArgs, which @devframes/hub's initHub composes its own hand-rolled server and command host on.

Note on the plan

An initial audit excluded packages/hub; during implementation the hub turned out to consume ws-bun, coerceAgentPositionalArgs, DevframeAgentHost, and createContextRpcServer, so those were kept (recorded in the plan's "Execution correction"). Net node trim is 9 exports, not 12.

Verification

pnpm lint, pnpm knip, pnpm test (1071 passing; tsnapi API snapshots regenerated and reviewed — the diff shows exactly the intended surface change), pnpm typecheck (26 packages), and pnpm build all pass.

This is a breaking change targeted at 0.9; releasing is a separate step requiring human approval.


This PR was created with the help of an agent.

antfubot and others added 2 commits August 10, 2026 14:44
Trim both packages' published surface down to what integrations actually
consume, and move the primary authoring helper to the package root.

devframe:
- Move `defineDevframe` onto the `devframe` root entry (next to
  `defineRpcFunction`); `devframe/types` is now strictly type-only. `devframe`
  is the canonical import for both values and types.
- Remove dead subpaths: `devframe/adapters/embedded` (a one-line wrapper around
  `def.setup(ctx)`), `devframe/utils/hash`, `devframe/utils/promise`,
  `devframe/utils/scope` (no integration consumers).
- Slim `devframe/node` to the server-assembly surface, dropping 9 internal
  exports (diagnostics/services/views host classes, the shared-state/streaming/
  scope/settings factories, and the toDialableHost/formatHostForUrl helpers).
  `createContextRpcServer`, `DevframeAgentHost`, and `coerceAgentPositionalArgs`
  stay public — `@devframes/hub`'s `initHub` composes its own hand-rolled server
  and command host on them.

@devframes/hub:
- Export `DEFAULT_CATEGORIES_ORDER` only from `@devframes/hub/constants`; drop
  the redundant re-exports from `.`, `/node`, and `/client`.

All in-repo consumers (plugins, examples, packages) are migrated to the new
import paths, docs/skill/templates are swept, and `docs/guide/migration-0.9.md`
documents every change. `devframe/rpc/transports/ws-bun` is retained (the hub
uses it) despite the original plan flagging it for removal.

Co-authored-by: opencode <noreply@opencode.ai>
@netlify

netlify Bot commented Aug 10, 2026

Copy link
Copy Markdown

Deploy Preview for devfra ready!

Name Link
🔨 Latest commit 0458941
🔍 Latest deploy log https://app.netlify.com/projects/devfra/deploys/6a7ab4f12fdf8d00091cf580
😎 Deploy Preview https://deploy-preview-190--devfra.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

antfubot and others added 3 commits August 11, 2026 01:10
Restore the `devframe/adapters/embedded` entry point (`createEmbedded`) that the
0.9 surface reduction had removed — kept as a named, discoverable adapter
alongside cac/dev/build/mcp. Re-adds the export map / tsdown / alias plumbing,
the source, the docs page + nav + adapter tables, the SKILL row, and the tsnapi
snapshot, and drops the corresponding migration-0.9 note.

Co-authored-by: opencode <noreply@opencode.ai>
…rame/internal

- Restore `devframe/utils/hash` — kept as a public utility (maintainer request).
- Add a new `devframe/internal` entry point for the low-level primitives shared
  only between `devframe` and `@devframes/hub`, and relocate `createContextRpcServer`,
  `DevframeAgentHost`, and `coerceAgentPositionalArgs` there from `devframe/node`.
  `devframe/internal` is an explicitly-unstable cross-package surface; the hub
  imports these three from it. This keeps the public `devframe/node` barrel to
  the genuinely-public server-assembly API.

Updates the migration guide, SKILL/utilities docs, knip entry list, plan, and
regenerates the tsnapi snapshots.

Co-authored-by: opencode <noreply@opencode.ai>
…e/internal

Reduce the public `devframe/node` barrel to the server-assembly surface only
(`createHostContext`, `createH3DevframeHost`, `startHttpAndWs`, `createStorage`,
`RpcFunctionsHost`). Relocate the low-level primitives that only first-party
integrations use to the unstable `devframe/internal` surface:

- the instance registry (`registerDevframeInstance` / `listLiveDevframeInstances`
  + `DevframeInstanceRecord` / `DevframeInstanceRegistration`)
- `isObject`, `normalizeHttpServerUrl`

`startHttpAndWs` stays on `devframe/node` — it's the primary programmatic
server entry (used as real code by several plugins, examples, and the hub), not
a low-level util. The inspect plugin and the hub host examples now import the
instance registry from `devframe/internal`; `@vitejs/devtools` picks up
`isObject`/`normalizeHttpServerUrl` from there too.

Co-authored-by: opencode <noreply@opencode.ai>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant